Skip to main content

Why a Knowledge Base?

You might be wondering why would you want a knowledge base (KB), when the documentation of your software can be contained in a standard PDF file. In this article you will learn why a knowledge base is a superior approach to software documentation.

If you need further persuasion, visit this Atlassian article.

1. Continuous Updates and Version Control​

In a Continuous Integration/Continuous Deployment workflow, documentation must evolve alongside your code to prevent mismatches. The Docs-as-Code approach manages your KB in a Git repository like GitHub, allowing team members to draft and test updates in separate branches before merging them into production. This setup provides complete version control, tracking history and comments so you can easily audit changes or roll back versions. Ultimately, treating documentation as code ensures users always access accurate, up-to-date information that matches your latest software releases.

Git Comment

2. Display Adaptiveness and Dark Theme​

Since the KB renders on the browser as a webpage, the display is adaptive and displays according to the device screen and the browser preferences. It is easy to switch between dark and light themes.

Switch to activate the dark theme of the knowledge base

3. Embedded Media​

Markdown allows to embed different types of media such as images and videos.

The following is an animaged gif image:

This is an animated gif image showing project media files

To learn about the possibilities for video in the Knowledge Base, visit the video library section.

4. LLMs Ready​

Large Language Models (LLMs) learn about software by processing websites and user manuals. While they can learn from various file types, they prefer Markdown language, since it is machine-readable and explicitly structures knowledge hierarchy and mark up. Key advantages of Markdown for LLMs:

  • Image Context: Models can read alt tags to reference images even if they aren't multimodal.

  • LLM-Specific Instructions: Allows embedding notes and guidance directly for model interpretation.

  • Metadata Support: Easily incorporates SEO tags and markers for crawlers and indexers.

Learn more at: Why Markdown is the Best Format for LLMs

5. Artifacts​

In a knowledge base that uses markdown it is possible to embed dynamic artifacts, for example:

5.1 Accordions​

Click here to expand and read more

This is the hidden content inside the accordion. You can put text, bullet points, or even images here:

  • Item one
  • Item two

5.2 Callouts​

note

This is a standard note callout to highlight important information.

tip

Here is a helpful tip or best practice you can share with users.

info

Use an info callout for general supplementary details.

warning

Be careful! This warns the user about a potential pitfall or breaking change.

danger

Critical warning! Use this for dangerous actions or destructive steps.

5.3 Diagrams​

The KB allows to use code (mermaid syntax) to create diagrams. Use diagrams to illustrate processes or decision-making. Since the diagrams are based on code and not images, they are very light even if they hold a lot of detail and they can be understood by both humans and llms.

Example:

To learn more about the possibilities of mermaid diagrams, visit the Diagrams section

5.4 Code Blocks​

If you need to communicate code that can be easily copy and pasted

function greetUser(name) {
console.log("Hello, " + name + "!");
}
greetUser("Developer");

5.5 HTML and JS ready​

This knowledge base uses MDX, which allows you to mix Markdown, raw HTML, and JavaScript right inside the article.

A . Standard HTML Styling​

You can use standard HTML tags with inline styles:

HTML Box: This element is written using raw HTML and CSS directly inside the Markdown file.

B. Interactive JavaScript / Scripts​

You can also attach event handlers and JavaScript functionality using JSX syntax:

6. LLM Assistant Ready​

The latest release of Chrome (and many other browsers) now includes an LLM assistant that helps users "talk" with the webpage. Because this website is built as a static HTML site derived from Markdown, it renders clean, semantic HTML and structure (such as clear heading hierarchies and alt tags) that makes it exceptionally effective for browser-based LLM assistants to understand the content.

Chrome browser showing the Gemini assistant tab explaining the KB article

7. Search and Share​

It is easy to integrate local search in the KB using React components. You can test it now, it quickly searches across all articles in the knowledge base:

copy a link that points to specific sections'

In addition to local search functionality, Google will index the KB considering the knowledge hierarchy as established in the sitemap.xml file that is automatically generated by docusaurus on every KB build run . View the sitemap

To share knowledge, instead of sharing a link to the KB, share a link to a specific section in a specific article. To do this, simply copy the anchor link found at the end of each heading.

copy a link that points to specific sections'

8. Analytics​

It is possible to know which are the most reviewed articles and sections of the documentation. In the case of this knowledge base I have placed a Google Analytics Tag , so on my GA4 dashboard I can see which audiences are visiting, what they are reading and for how long. GA4 dashboard with stats about visitors to the knowledge base

Also you can get instant feedback from the user's experience with the "Was this useful" widget, so you can implement a natural selection evolution approach to the curation of the knowledge base. Find the vote option at the bottom of the article was this page useful

9. Data Sovereignty​

This KB relies entirely on open-source technologies, meaning no third party controls its display or vendor-locks your content.

Unlike commercial platforms such as Readme and GitBook—which force you to depend on proprietary hosting and tooling—the system generating this KB runs locally on your computer. You retain complete ownership and can migrate your hosting provider or deploy to any cloud compute or container platform at any time.

11 . Batch edits​

Since the documentation is code, you can edit it using code tools like Find and Replace. In the following image I'm replacing the word 'demo' with 'trial' across all articles in the knowledge base

Using Find and Replace in Visual Studio Code to replace 'demo' with 'trial'

12. Navigation and knowledge hierarchy​

The left sidebar maps all sections and articles for easy navigation, while the right-side floating table of contents helps you track your place and jump between sections quickly. This follows the latest trends in best documentation practices.

13. Be the leading source of truth for your software​

In a world where LLMs can be used to render stories that cater to the interests of whoever is using them, an official knowledge base is perhaps the best way to maintain editorial control over how your product is explained to the world.

Develop arguments that support your claims so that users understand not only how the software functions, but also the design principles behind it. A knowledge base can be much more than a user's manual—it can articulate why people should use your software, effectively serving as a platform that advances your value proposition.

For example, in the case of XLeap, the KB can be the place where people learn why anonymity when sharing ideas during a collaborative session leads to better meeting outcomes.

14. Reduce customer support ticket volume​

First touch point in your customer service/client success/training pipeline. To reduce the volume of support tickets, have your users first consult the Knowledge Base, and after using the search engine (or a support chatbot) they will check an article only if the article/chatbot was unable to be useful route the user to a ticket system for personal support. Then you are able to know which articles they read and determine why is it that the article wasn't enough.

Was this page helpful?